From e962c2f3526292f0cea1dda6ca3980874eeb3ac5 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Tue, 14 Mar 2023 18:11:30 -0400 Subject: [PATCH] Add docs and fix annotations for ostree-repo-file.c The code here is not great, embarassing we've gone this long without docs for some of these public API functions too. I think this is right though. --- rust-bindings/src/auto/repo_file.rs | 8 ++-- rust-bindings/src/auto/versions.txt | 2 +- rust-bindings/sys/src/auto/versions.txt | 2 +- src/libostree/ostree-repo-file.c | 51 +++++++++++++++++++++++++ 4 files changed, 57 insertions(+), 6 deletions(-) diff --git a/rust-bindings/src/auto/repo_file.rs b/rust-bindings/src/auto/repo_file.rs index 31fe363c..d480e763 100644 --- a/rust-bindings/src/auto/repo_file.rs +++ b/rust-bindings/src/auto/repo_file.rs @@ -77,28 +77,28 @@ impl RepoFile { } #[doc(alias = "ostree_repo_file_tree_get_contents")] - pub fn tree_get_contents(&self) -> glib::Variant { + pub fn tree_get_contents(&self) -> Option { unsafe { from_glib_full(ffi::ostree_repo_file_tree_get_contents(self.to_glib_none().0)) } } #[doc(alias = "ostree_repo_file_tree_get_contents_checksum")] - pub fn tree_get_contents_checksum(&self) -> glib::GString { + pub fn tree_get_contents_checksum(&self) -> Option { unsafe { from_glib_none(ffi::ostree_repo_file_tree_get_contents_checksum(self.to_glib_none().0)) } } #[doc(alias = "ostree_repo_file_tree_get_metadata")] - pub fn tree_get_metadata(&self) -> glib::Variant { + pub fn tree_get_metadata(&self) -> Option { unsafe { from_glib_full(ffi::ostree_repo_file_tree_get_metadata(self.to_glib_none().0)) } } #[doc(alias = "ostree_repo_file_tree_get_metadata_checksum")] - pub fn tree_get_metadata_checksum(&self) -> glib::GString { + pub fn tree_get_metadata_checksum(&self) -> Option { unsafe { from_glib_none(ffi::ostree_repo_file_tree_get_metadata_checksum(self.to_glib_none().0)) } diff --git a/rust-bindings/src/auto/versions.txt b/rust-bindings/src/auto/versions.txt index c9131191..c5cd5662 100644 --- a/rust-bindings/src/auto/versions.txt +++ b/rust-bindings/src/auto/versions.txt @@ -1,2 +1,2 @@ Generated by gir (https://github.com/gtk-rs/gir @ 0eeebbdf9d4d) -from gir-files (@ f4ba299323ae) +from gir-files (@ ed64a300c33e) diff --git a/rust-bindings/sys/src/auto/versions.txt b/rust-bindings/sys/src/auto/versions.txt index c9131191..c5cd5662 100644 --- a/rust-bindings/sys/src/auto/versions.txt +++ b/rust-bindings/sys/src/auto/versions.txt @@ -1,2 +1,2 @@ Generated by gir (https://github.com/gtk-rs/gir @ 0eeebbdf9d4d) -from gir-files (@ f4ba299323ae) +from gir-files (@ ed64a300c33e) diff --git a/src/libostree/ostree-repo-file.c b/src/libostree/ostree-repo-file.c index a6be8988..de606b0a 100644 --- a/src/libostree/ostree-repo-file.c +++ b/src/libostree/ostree-repo-file.c @@ -269,6 +269,15 @@ do_resolve_nonroot (OstreeRepoFile *self, return TRUE; } +/** + * ostree_repo_file_ensure_resolved: + * @self: A repo file + * @error: Error + * + * Ensure that the backing metadata is loaded. + * + * Returns: %FALSE if the operation failed, %TRUE otherwise + */ gboolean ostree_repo_file_ensure_resolved (OstreeRepoFile *self, GError **error) @@ -321,18 +330,42 @@ ostree_repo_file_get_xattrs (OstreeRepoFile *self, return TRUE; } +/** + * ostree_repo_file_tree_get_contents: + * @self: A repo file + * + * This API will return %NULL if the file is not "resolved" i.e. in a loaded + * state. It will also return %NULL if this path is not a directory tree. + * + * Returns: (nullable): The GVariant representing the children of this directory. + */ GVariant * ostree_repo_file_tree_get_contents (OstreeRepoFile *self) { return self->tree_contents; } +/** + * ostree_repo_file_tree_get_metadata: + * @self: A repo file + * + * This API will return %NULL if the file is not "resolved" i.e. in a loaded + * state. It will also return %NULL if this path is not a directory tree. + * + * Returns: (nullable): The GVariant representing the metadata for this directory. + */ GVariant * ostree_repo_file_tree_get_metadata (OstreeRepoFile *self) { return self->tree_metadata; } +/** + * ostree_repo_file_tree_set_metadata: + * @self: A repo file + * + * Replace the metadata checksum and metadata object. + */ void ostree_repo_file_tree_set_metadata (OstreeRepoFile *self, const char *checksum, @@ -344,12 +377,24 @@ ostree_repo_file_tree_set_metadata (OstreeRepoFile *self, self->tree_metadata_checksum = g_strdup (checksum); } +/** + * ostree_repo_file_tree_get_contents_checksum: + * @self: A repo file + * + * Returns: (nullable): The SHA256 digest of the content object, or %NULL if this is not a directory. + */ const char * ostree_repo_file_tree_get_contents_checksum (OstreeRepoFile *self) { return self->tree_contents_checksum; } +/** + * ostree_repo_file_tree_get_metadata_checksum: + * @self: A repo file + * + * Returns: (nullable): The SHA256 digest of the metadata object, or %NULL if this is not a directory. + */ const char * ostree_repo_file_tree_get_metadata_checksum (OstreeRepoFile *self) { @@ -384,6 +429,12 @@ ostree_repo_file_get_root (OstreeRepoFile *self) return parent; } +/** + * ostree_repo_file_tree_get_checksum: + * @self: A repo file + * + * Returns: For non-directories, the SHA-256 digest of the object. For directories, the metadata digest will be returned. + */ const char * ostree_repo_file_get_checksum (OstreeRepoFile *self) { -- 2.30.2